Skip Headers

Oracle® XML DB Developer's Guide 10g Release 2 (10.2) Part Number B14259-02 |
Home | Book List | Contents | Index | Master Index | Feedback

Previous | Next
| View PDF

# 8 XML Schema Evolution

This chapter describes how you can update your XML schema after you have registered it with Oracle XML DB. XML schema evolution is the process of updating your registered XML schema.

This chapter contains these topics:

- Overview of XML Schema Evolution

- Guidelines for Using Procedure DBMS_XMLSCHEMA.COPYEVOLVE

- Revised Purchase-Order XML Schema

- Style Sheet to Update Existing Instance Documents

- Procedure DBMS_XMLSCHEMA.COPYEVOLVE: Parameters and Errors

- Using Procedure DBMS_XMLSCHEMA.COPYEVOLVE

## Overview of XML Schema Evolution

Oracle XML DB supports the W3C XML Schema recommendation. XML instance documents that conform to an XML schema can be stored and retrieved using SQL and protocols such as FTP, HTTP(S), and WebDAV. In addition to specifying the structure of XML documents, XML schemas determine the mapping between XML and object-relational storage.

See Also: Chapter 5, "XML Schema Storage and Query: Basic"

Oracle XML DB supports XML schema evolution by providing PL/SQL procedure `copyEvolve` as part of PL/SQL package `DBMS_XMLSCHEMA`. Procedure `copyEvolve` copies existing instance documents to temporary `XMLType` tables to back them up, drops the old version of the XML schema (which also deletes the associated instance documents), registers the new version, and copies the backed-up instance documents to new `XMLType` tables.

With procedure `copyEvolve` you can evolve your registered XML schema in such a way that existing XML instance documents continue to be valid. If you do not care about the existing documents, you can simply drop the `XMLType` tables that are dependent on the XML schema, delete the old XML schema, and register the new XML schema at the same URL.

### Limitations of Procedure DBMS_XMLSCHEMA.COPYEVOLVE

The following are the limitations of procedure `DBMS_XMLSCHEMA.copyEvolve`:

- Indexes, triggers, constraints, RLS policies and other metadata related to the `XMLType` tables that are dependent on the schemas that are evolved, will not be preserved. These must be re-created after evolution.

- If top-level element names are being changed, there are more steps to be followed after procedure `copyEvolve` completes executing. See the section on "Top-Level Element Name Changes" for more details.

- Data copy-based evolution cannot be used if there is a table with an object-type column that has an `XMLType` attribute that is dependent on any of the schemas to be evolved. For example, consider a table TAB1 that is created in the following way:

      CREATE TYPE t1 AS OBJECT (n NUMBER, x XMLType);
      CREATE TABLE tab1 (e NUMBER, o t1) XMLType
               COLUMN o.x XMLSchema "s1.xsd"
               ELEMENT "Employee";

  The example assumes that an XML schema with a top-level element `Employee` has been registered under URL `s1.xsd`. It is not possible to evolve this XML schema since table `TAB1` with column `O` with `XMLType` attribute `X` is dependent on this XML schema.

## Guidelines for Using Procedure DBMS_XMLSCHEMA.COPYEVOLVE

Here are some guidelines for using procedure `DBMS_XMLSCHEMA.copyEvolve`:

1. First, identify the XML schemas that are dependent on the XML schema that is to be evolved. You can acquire the URLs of the dependent XML schemas using the following query, where `schema_to_be_evolved` is the schema to be evolved, and `owner_of_schema_to_be_evolved` is its owner (database user).

       SELECT dxs.SCHEMA_URL
           FROM DBA_DEPENDENCIES dd, DBA_XML_SCHEMAS dxs
           WHERE dd.REFERENCED_NAME = (SELECT INT_OBJNAME
                                         FROM DBA_XML_SCHEMAS
                                         WHERE SCHEMA_URL = schema_to_be_evolved
                                           AND OWNER = schema_to_be_evolved)
             AND dxs.OWNER = owner_of_schema_to_be_evolved
             AND dxs.INT_OBJNAME = dd.NAME;

   In many cases, no changes may be necessary in the dependent XML schemas. But if the dependent XML schemas need to be changed, you must also prepare new versions of those XML schemas.

2. If the existing instance documents do not conform to the new XML schema, you must provide an XSL style sheet that, when applied to an instance document, will transform it to conform to the new schema. This needs to be done for each XML schema identified in Step 1. The transformation must handle documents that conform to all top-level elements in the new XML schema.

3. Call procedure `DBMS_XMLSCHEMA.copyEvolve`, specifying the XML schema URLs, new schemas, and transformations.

### Top-Level Element Name Changes

Procedure `DBMS_XMLSCHEMA.copyEvolve` assumes that top-level elements have not been dropped and that their names have not been changed in the new XML schemas. If there are such changes in your new XML schemas, you can call procedure `copyEvolve` with the `generateTables` parameter set to FALSE and the `preserveOldDocs` parameter set to TRUE. In this way new tables are generated and the temporary tables holding the old documents are not dropped at the end of the procedure. You can then store the old documents in whatever form is appropriate and drop the temporary tables. See "Procedure DBMS_XMLSCHEMA.COPYEVOLVE: Parameters and Errors" for more details on the using these parameters.

### Ensure that the XML Schema and Dependents are Not Used by Concurrent Sessions

Ensure that the XML schema and its dependents are not used by any concurrent session during the XML schema evolution process. If other concurrent sessions have shared locks on this schema at the beginning of the evolution process, then procedure `DBMS_XMLSCHEMA.copyEvolve` waits for these sessions to release the locks so that it can acquire an exclusive lock. However this lock is released immediately to allow the rest of the process to continue.

### Rollback When Procedure DBMS_XMLSCHEMA.COPYEVOLVE Raises an Error

Procedure `DBMS_XMLSCHEMA.copyEvolve()` either completely succeeds or raises an error, in which case it attempts to rollback as much of the operation as possible. Evolving a schema involves many database DDL statements. When an error occurs, compensating DDL statements are executed to undo the effect of all steps executed to that point. If the old tables/schemas have been dropped they are re-created but any table/column/storage properties and auxiliary structures associated with the tables/columns like indexes, triggers, constraints, and RLS policies are lost.

### Failed Rollback From Insufficient Privileges

In certain cases you cannot rollback the operation. For example, if table creation fails due to reasons not related to the new schema, such as, from insufficient privileges, there is no way to rollback. The temporary tables are not deleted even if `preserveOldDocs` is false, so that the data can be recovered. If the `mapTabName` parameter is null, the mapping table name is `XDB$MAPTAB` followed by a sequence number. The exact table name can be found using a query such as:

    SELECT TABLE_NAME FROM USER_TABLES WHERE TABLE_NAME LIKE 'XDB$MAPTAB%';

### Privileges Needed for XML Schema Evolution

Schema evolution may involve dropping/creating types. Hence you need type-related privileges such as `DROP TYPE`, `CREATE TYPE`, and `ALTER TYPE`.

You need privileges to delete and register the XML schemas involved in the evolution. You need all privileges on `XMLType` tables that conform to the schemas being evolved. For `XMLType` columns, the `ALTER TABLE` privilege is needed on corresponding tables. If there are schema-based `XMLType` tables or columns in other database schemas, you need privileges such as the following:

- `CREATE ANY TABLE`

- `CREATE ANY INDEX`

- `SELECT ANY TABLE`

- `UPDATE ANY TABLE`

- `INSERT ANY TABLE`

- `DELETE ANY TABLE`

- `DROP ANY TABLE`

- `ALTER ANY TABLE`

- `DROP ANY INDEX`

To avoid having to grant all these privileges to the schema owner, Oracle recommends that the evolution be performed by a DBA if there are XML schema-based `XMLType` table or columns in other users' database schemas.

## Revised Purchase-Order XML Schema

Example 8-1 shows a partial listing of a revised version of the purchase-order XML schema of Example 3-8. See Example D-2 for the complete revised schema listing. Text that is in bold face here is new or significantly different from that in the original schema (Example 3-8).

Example 8-1 Revised Purchase-Order XML Schema

    <xs:schema xmlns:xs="http://www.w3.org/2001/XMLSchema"
               xmlns:xdb="http://xmlns.oracle.com/xdb"
               version="1.0">
      <xs:element
        name="PurchaseOrder" type="PurchaseOrderType"
        xdb:defaultTable="PURCHASEORDER"
        xdb:columnProps=
          "CONSTRAINT purchaseorder_pkey PRIMARY KEY (XMLDATA.reference),
           CONSTRAINT valid_email_address FOREIGN KEY (XMLDATA.userid)
             REFERENCES hr.employees (EMAIL)"
        xdb:tableProps=
          "VARRAY XMLDATA.ACTIONS.ACTION STORE AS TABLE ACTION_TABLE
            ((CONSTRAINT action_pkey PRIMARY KEY (NESTED_TABLE_ID, SYS_NC_ARRAY_INDEX$)))
           VARRAY XMLDATA.LINEITEMS.LINEITEM STORE AS TABLE LINEITEM_TABLE
            ((constraint LINEITEM_PKEY primary key (NESTED_TABLE_ID, SYS_NC_ARRAY_INDEX$)))
           lob (XMLDATA.NOTES) STORE AS (ENABLE STORAGE IN ROW STORAGE(INITIAL 4K NEXT 32K))"/>
      <xs:complexType name="PurchaseOrderType" xdb:SQLType="PURCHASEORDER_T">
        <xs:sequence>
          <xs:element name="Actions" type="ActionsType" xdb:SQLName="ACTIONS"/>
          <xs:element name="Reject" type="RejectionType" minOccurs="0" xdb:SQLName="REJECTION"/>
          <xs:element name="Requestor" type="RequestorType" xdb:SQLName="REQUESTOR"/>
          <xs:element name="User" type="UserType" xdb:SQLName="USERID"/>
          <xs:element name="CostCenter" type="CostCenterType" xdb:SQLName="COST_CENTER"/>
          <xs:element name="BillingAddress" type="AddressType" minOccurs="0"
                      xdb:SQLName="BILLING_ADDRESS"/>
          <xs:element name="ShippingInstructions" type="ShippingInstructionsType"
                      xdb:SQLName="SHIPPING_INSTRUCTIONS"/>
          <xs:element name="SpecialInstructions" type="SpecialInstructionsType"
                      xdb:SQLName="SPECIAL_INSTRUCTIONS"/>
          <xs:element name="LineItems" type="LineItemsType" xdb:SQLName="LINEITEMS"/>
          <xs:element name="Notes" type="NotesType" minOccurs="0" xdb:SQLType="CLOB"
                      xdb:SQLName="NOTES"/>
        </xs:sequence>
        <xs:attribute name="Reference" type="ReferenceType" use="required" xdb:SQLName="REFERENCE"/>
        <xs:attribute name="DateCreated" type="xs:dateTime" use="required"
                      xdb:SQLType="TIMESTAMP WITH TIME ZONE"/>
      </xs:complexType>
      <xs:complexType name="LineItemsType" xdb:SQLType="LINEITEMS_T">
        <xs:sequence>
          <xs:element name="LineItem" type="LineItemType" maxOccurs="unbounded" xdb:SQLName="LINEITEM"
                      xdb:SQLCollType="LINEITEM_V"/>
        </xs:sequence>
      </xs:complexType>
      <xs:complexType name="LineItemType" xdb:SQLType="LINEITEM_T">
        <xs:sequence>
          <xs:element name="Part" type="PartType" xdb:SQLName="PART"/>
          <xs:element name="Quantity" type="quantityType"/>
        </xs:sequence>
        <xs:attribute name="ItemNumber" type="xs:integer" xdb:SQLName="ITEMNUMBER"
                      xdb:SQLType="NUMBER"/>
      </xs:complexType>
      <xs:complexType name="PartType" xdb:SQLType="PART_T">
        <xs:simpleContent>
          <xs:extension base="UPCCodeType">
            <xs:attribute name="Description" type="DescriptionType" use="required"
                          xdb:SQLName="DESCRIPTION"/>
            <xs:attribute name="UnitCost" type="moneyType" use="required"/>
          </xs:extension>
        </xs:simpleContent>
      </xs:complexType>
      <xs:simpleType name="ReferenceType">
        <xs:restriction base="xs:string">
          <xs:minLength value="18"/>
          <xs:maxLength value="30"/>
        </xs:restriction>
      </xs:simpleType>

    . . .

      <xs:complexType name="RejectionType" xdb:SQLType="REJECTION_T">
        <xs:all>
          <xs:element name="User" type="UserType" minOccurs="0" xdb:SQLName="REJECTED_BY"/>
          <xs:element name="Date" type="DateType" minOccurs="0" xdb:SQLName="DATE_REJECTED"/>
          <xs:element name="Comments" type="CommentsType" minOccurs="0" xdb:SQLName="REASON_REJECTED"/>
        </xs:all>
      </xs:complexType>
      <xs:complexType name="ShippingInstructionsType" xdb:SQLType="SHIPPING_INSTRUCTIONS_T">
        <xs:sequence>
          <xs:element name="name" type="NameType" minOccurs="0" xdb:SQLName="SHIP_TO_NAME"/>
          <xs:choice>
            <xs:element name="address" type="AddressType" minOccurs="0"/>
            <xs:element name="fullAddress" type="FullAddressType" minOccurs="0"
                        xdb:SQLName="SHIP_TO_ADDRESS"/>
          </xs:choice>
          <xs:element name="telephone" type="TelephoneType" minOccurs="0" xdb:SQLName="SHIP_TO_PHONE"/>
        </xs:sequence>
      </xs:complexType>

    . . .

      <xs:simpleType name="NameType">
        <xs:restriction base="xs:string">
          <xs:minLength value="1"/>
          <xs:maxLength value="20"/>
        </xs:restriction>
      </xs:simpleType>
      <xs:simpleType name="FullAddressType">
        <xs:restriction base="xs:string">
          <xs:minLength value="1"/>
          <xs:maxLength value="256"/>
        </xs:restriction>
      </xs:simpleType>

    . . .

      <xs:simpleType name="DescriptionType">
        <xs:restriction base="xs:string">
          <xs:minLength value="1"/>
          <xs:maxLength value="256"/>
        </xs:restriction>
      </xs:simpleType>
      <xs:complexType name="AddressType" xdb:SQLType="ADDRESS_T">
        <xs:sequence>
          <xs:element name="StreetLine1" type="StreetType"/>
          <xs:element name="StreetLine2" type="StreetType" minOccurs="0"/>
          <xs:element name="City" type="CityType"/>
          <xs:choice>
            <xs:sequence>
              <xs:element name="State" type="StateType"/>
              <xs:element name="ZipCode" type="ZipCodeType"/>
            </xs:sequence>
            <xs:sequence>
              <xs:element name="Province" type="ProvinceType"/>
              <xs:element name="PostCode" type="PostCodeType"/>
            </xs:sequence>
            <xs:sequence>
              <xs:element name="County" type="CountyType"/>
              <xs:element name="Postcode" type="PostCodeType"/>
            </xs:sequence>
          </xs:choice>
          <xs:element name="Country" type="CountryType"/>
        </xs:sequence>
      </xs:complexType>
      <xs:simpleType name="StreetType">
        <xs:restriction base="xs:string">
          <xs:minLength value="1"/>
          <xs:maxLength value="128"/>
        </xs:restriction>
      </xs:simpleType>
      <xs:simpleType name="CityType">
        <xs:restriction base="xs:string">
          <xs:minLength value="1"/>
          <xs:maxLength value="64"/>
        </xs:restriction>
      </xs:simpleType>
      <xs:simpleType name="StateType">
        <xs:restriction base="xs:string">
          <xs:minLength value="2"/>
          <xs:maxLength value="2"/>
          <xs:enumeration value="AK"/>
          <xs:enumeration value="AL"/>
          <xs:enumeration value="AR"/>

     . . . -- A value for each US state abbreviation

          <xs:enumeration value="WY"/>
        </xs:restriction>
      </xs:simpleType>
      <xs:simpleType name="ZipCodeType">
        <xs:restriction base="xs:string">
          <xs:pattern value="\d{5}"/>
          <xs:pattern value="\d{5}-\d{4}"/>
        </xs:restriction>
      </xs:simpleType>
      <xs:simpleType name="CountryType">
        <xs:restriction base="xs:string">
          <xs:minLength value="1"/>
          <xs:maxLength value="64"/>
        </xs:restriction>
      </xs:simpleType>
      <xs:simpleType name="CountyType">
        <xs:restriction base="xs:string">
          <xs:minLength value="1"/>
          <xs:maxLength value="32"/>
        </xs:restriction>
      </xs:simpleType>
      <xs:simpleType name="PostCodeType">
        <xs:restriction base="xs:string">
          <xs:minLength value="1"/>
          <xs:maxLength value="12"/>
        </xs:restriction>
      </xs:simpleType>
      <xs:simpleType name="ProvinceType">
        <xs:restriction base="xs:string">
          <xs:minLength value="2"/>
          <xs:maxLength value="2"/>
        </xs:restriction>
      </xs:simpleType>
      <xs:simpleType name="NotesType">
        <xs:restriction base="xs:string">
          <xs:maxLength value="32767"/>
        </xs:restriction>
      </xs:simpleType>
      <xs:simpleType name="UPCCodeType">
        <xs:restriction base="xs:string">
          <xs:minLength value="11"/>
          <xs:maxLength value="14"/>
          <xs:pattern value="\d{11}"/>
          <xs:pattern value="\d{12}"/>
          <xs:pattern value="\d{13}"/>
          <xs:pattern value="\d{14}"/>
        </xs:restriction>
      </xs:simpleType>
    </xs:schema>

Note: As always: SQL is case-insensitive, but names in SQL code are implicitly uppercase, unless you enclose them in double-quotes. XML is case-sensitive. You must refer to SQL names in XML code using the correct case: uppercase SQL names must be written as uppercase. For example, if you create a table named `my_table` in SQL without using double-quotes, then you must refer to it in XML as "`MY_TABLE`".

## Style Sheet to Update Existing Instance Documents

After you modify a registered XML schema, you must also update any existing XML instance documents that used the old version of the schema. You do this by applying an XSLT style sheet to each of the instance documents. The style sheet represents the difference between the old and new schemas.

Example 8-2 is a style sheet, in file `evolvePurchaseOrder.xsl`, that transforms existing purchase-order documents that use the old schema, so they will use the new schema instead.

Example 8-2 evolvePurchaseOrder.xsl: Style Sheet to Update Instance Documents

    <?xml version="1.0" encoding="UTF-8"?>
    <xsl:stylesheet
      version="1.0"
      xmlns:xsl="http://www.w3.org/1999/XSL/Transform"
      xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance">
      <xsl:output method="xml" encoding="UTF-8"/>
      <xsl:template match="/PurchaseOrder">
        <PurchaseOrder>
          <xsl:attribute name="xsi:noNamespaceSchemaLocation">
            http://localhost:8080/source/schemas/poSource/xsd/purchaseOrder.xsd
          </xsl:attribute>
          <xsl:for-each select="Reference">
            <xsl:attribute name="Reference">
              <xsl:value-of select="."/>
            </xsl:attribute>
          </xsl:for-each>
          <xsl:variable name="V264_394" select="'2004-01-01T12:00:00.000000-08:00'"/>
          <xsl:attribute name="DateCreated">
            <xsl:value-of select="$V264_394"/>
          </xsl:attribute>
          <xsl:for-each select="Actions">
            <Actions>
              <xsl:for-each select="Action">
                <Action>
                  <xsl:for-each select="User">
                    <User>
                      <xsl:value-of select="."/>
                    </User>
                  </xsl:for-each>
                  <xsl:for-each select="Date">
                    <Date>
                      <xsl:value-of select="."/>
                    </Date>
                  </xsl:for-each>
                </Action>
              </xsl:for-each>
            </Actions>
          </xsl:for-each>
          <xsl:for-each select="Reject">
            <Reject>
              <xsl:for-each select="User">
                <User>
                  <xsl:value-of select="."/>
                </User>
              </xsl:for-each>
              <xsl:for-each select="Date">
                <Date>
                  <xsl:value-of select="."/>
                </Date>
              </xsl:for-each>
              <xsl:for-each select="Comments">
                <Comments>
                  <xsl:value-of select="."/>
                </Comments>
              </xsl:for-each>
            </Reject>
          </xsl:for-each>
          <xsl:for-each select="Requestor">
            <Requestor>
              <xsl:value-of select="."/>
            </Requestor>
          </xsl:for-each>
          <xsl:for-each select="User">
            <User>
              <xsl:value-of select="."/>
            </User>
          </xsl:for-each>
          <xsl:for-each select="CostCenter">
            <CostCenter>
              <xsl:value-of select="."/>
            </CostCenter>
          </xsl:for-each>
          <ShippingInstructions>
            <xsl:for-each select="ShippingInstructions">
              <xsl:for-each select="name">
                <name>
                  <xsl:value-of select="."/>
                </name>
              </xsl:for-each>
            </xsl:for-each>
            <xsl:for-each select="ShippingInstructions">
              <xsl:for-each select="address">
                <fullAddress>
                  <xsl:value-of select="."/>
                </fullAddress>
              </xsl:for-each>
            </xsl:for-each>
            <xsl:for-each select="ShippingInstructions">
              <xsl:for-each select="telephone">
                <telephone>
                  <xsl:value-of select="."/>
                </telephone>
              </xsl:for-each>
            </xsl:for-each>
          </ShippingInstructions>
          <xsl:for-each select="SpecialInstructions">
            <SpecialInstructions>
              <xsl:value-of select="."/>
            </SpecialInstructions>
          </xsl:for-each>
          <xsl:for-each select="LineItems">
            <LineItems>
              <xsl:for-each select="LineItem">
                <xsl:variable name="V22" select="."/>
                <LineItem>
                  <xsl:for-each select="@ItemNumber">
                    <xsl:attribute name="ItemNumber">
                      <xsl:value-of select="."/>
                    </xsl:attribute>
                  </xsl:for-each>
                  <xsl:for-each select="$V22/Part">
                    <xsl:variable name="V24" select="."/>
                    <xsl:for-each select="@Id">
                      <Part>
                        <xsl:for-each select="$V22/Description">
                          <xsl:attribute name="Description">
                            <xsl:value-of select="."/>
                          </xsl:attribute>
                        </xsl:for-each>
                        <xsl:for-each select="$V24/@UnitPrice">
                          <xsl:attribute name="UnitCost">
                            <xsl:value-of select="."/>
                          </xsl:attribute>
                        </xsl:for-each>
                        <xsl:value-of select="."/>
                      </Part>
                    </xsl:for-each>
                  </xsl:for-each>
                  <xsl:for-each select="$V22/Part">
                    <xsl:for-each select="@Quantity">
                      <Quantity>
                        <xsl:value-of select="."/>
                      </Quantity>
                    </xsl:for-each>
                  </xsl:for-each>
                </LineItem>
              </xsl:for-each>
            </LineItems>
          </xsl:for-each>
        </PurchaseOrder>
      </xsl:template>
    </xsl:stylesheet>

## Procedure DBMS_XMLSCHEMA.COPYEVOLVE: Parameters and Errors

Here is the signature of procedure `DBMS_XMLSCHEMA.copyEvolve`:

    procedure copyEvolve(schemaURLs       IN XDB$STRING_LIST_T,
                         newSchemas       IN XMLSequenceType,
                         transforms       IN XMLSequenceType := NULL,
                         preserveOldDocs  IN BOOLEAN := FALSE,
                         mapTabName       IN VARCHAR2 := NULL,
                         generateTables   IN BOOLEAN := TRUE,
                         force            IN BOOLEAN := FALSE,
                         schemaOwners     IN XDB$STRING_LIST_T := NULL);

Table 8-1 describes the individual parameters. Table 8-2 describes the errors associated with the procedure.

Table 8-1 Parameters of Procedure DBMS_XMLSCHEMA.COPYEVOLVE

Parameter | Description
--- | ---
`schemaURLs` | Varray of URLs of XML schemas to be evolved (varray of `VARCHAR2(4000)`. This should include the dependent schemas as well. Unless the force parameter is TRUE, the URLs should be in the dependency order, that is, if URL A comes before URL B in the varray, then schema A should not be dependent on schema B but schema B may be dependent on schema A.
`newSchemas` | Varray of new XML schema documents (`XMLType` instances). Specify this in exactly the same order as the corresponding URLs. If no change is necessary in an XML schema, provide the unchanged schema.
`transforms` | Varray of XSL documents (`XMLType` instances) that will be applied to XML schema based documents to make them conform to the new schemas. Specify these in exactly the same order as the corresponding URLs. If no transformations are required, this parameter need not be specified.
`preserveOldDocs` | If this is TRUE the temporary tables holding old data are not dropped at the end of schema evolution. See also "Using Procedure DBMS_XMLSCHEMA.COPYEVOLVE".
`mapTabName` | Specifies the name of table that maps old `XMLType` table or column names to names of corresponding temporary tables.
`generateTables` | By default this parameter is TRUE; if this is FALSE, `XMLType` tables or columns will not be generated after registering new schemas. If this is FALSE, `preserveOldDocs` must be TRUE and `mapTabName` must not be `NULL`.
`force` | If this is TRUE errors during the registration of new schemas are ignored. If there are circular dependencies among the schemas, set this flag to TRUE to ensure that each schema is stored even though there may be errors in registration.
`schemaOwners` | Varray of names of schema owners. Specify these in exactly the same order as the corresponding URLs.

Table 8-2 Errors Associated with Procedure DBMS_XMLSCHEMA.COPYEVOLVE

Error Number and Message | Cause | Action
--- | --- | ---
30942 XML Schema Evolution error for schema '<schema_url>' table "<owner_name>.<table_name>" column '<column_name>' | The given `XMLType` table or column that conforms to the given schema had errors during evolution. In the case of a table the column name will be empty. See also the more specific error that follows this. | Based on the schema, table, and column information in this error and the more specific error that follows, take corrective action.
30943 XML Schema '<schema_url>' is dependent on XML schema '<schema_url>' | Not all dependent XML schemas were specified or the schemas were not specified in dependency order, that is, if schema S1 is dependent on schema S, S must appear before S1. | Include the previously unspecified schema in the list of schemas or correct the order in which the schemas are specified. Then retry the operation.
30944 Error during rollback for XML schema '<schema_url>' table "<owner_name>.<table_name>" column '<column_name>' | The given `XMLType` table or column that conforms to the given schema had errors during a rollback of XML schema evolution. For a table the column name will be empty. See also the more specific error that follows this. | Based on the schema, table, and column information in this error and the more specific error that follows, take corrective action.
30945 Could not create mapping table '<table_name>' | A mapping table could not be created during XML schema evolution. See also the more specific error that follows this. | Ensure that a table with the given name does not exist and retry the operation.
30946 XML Schema Evolution warning: temporary tables not cleaned up | An error occurred after the schema was evolved while cleaning up temporary tables. The schema evolution was successful. | If you need to remove the temporary tables, use the mapping table to get the temporary table names and drop them.

## Using Procedure DBMS_XMLSCHEMA.COPYEVOLVE

Example 8-3 Loading Revised XML Schema and XSL Style Sheet

This example loads the revised XML schema and the evolution XSL style sheet into the Oracle XML DB repository.

    DECLARE
      res BOOLEAN;
    BEGIN
      res := DBMS_XDB.createResource(               -- Load revised XML schema
               '/source/schemas/poSource/revisedPurchaseOrder.xsd',
               bfilename('XMLDIR', 'revisedPurchaseOrder.xsd'),
               nls_charset_id('AL32UTF8'));
      res := DBMS_XDB.createResource(               -- Load revised XSL style sheet
               '/source/schemas/poSource/evolvePurchaseOrder.xsl',
               bfilename('XMLDIR', 'evolvePurchaseOrder.xsl'),
               nls_charset_id('AL32UTF8'));
    END;/

Example 8-4 shows how to use procedure `DBMS_XMLSCHEMA.copyEvolve` to evolve the purchase-order XML schema.

Example 8-4 Using DBMS_XMLSCHEMA.COPYEVOLVE to Update an XML Schema

This example evolves XML schema `purchaseOrder.xsd` to `revisedPurchaseOrder.xsd` using XSL style sheet `evolvePurchaseOrder.xsl`.

    BEGIN
      DBMS_XMLSCHEMA.copyEvolve(
        xdb$string_list_t('http://localhost:8080/source/schemas/poSource/xsd/purchaseOrder.xsd'),
        XMLSequenceType(XDBURIType('/source/schemas/poSource/revisedPurchaseOrder.xsd').getXML()),
        XMLSequenceType(XDBURIType('/source/schemas/poSource/evolvePurchaseOrder.xsl').getXML()));
    END;

    SELECT extract(object_value, '/PurchaseOrder/LineItems/LineItem[1]') LINE_ITEM
      FROM purchaseorder
      WHERE existsNode(object_value, '/PurchaseOrder[@Reference="SBELL-2003030912333601PDT"]') = 1
    /

    LINE_ITEM
    ------------------------------------------------------------------------------
    <LineItem ItemNumber="1">
      <Part Description="A Night to Remember" UnitCost="39.95">715515009058</Part>
      <Quantity>2</Quantity>
    </LineItem>

The same query would have produced the following result before the schema evolution:

    LINE_ITEM
    ----------------------------------------------------------
    <LineItem ItemNumber="1">
      <Description>A Night to Remember</Description>
      <Part Id="715515009058" UnitPrice="39.95" Quantity="2"/>
    </LineItem>

Procedure `DBMS_XMLSCHEMA.copyEvolve` is used to evolve registered XML schemas in such a way that existing XML instances continue to remain valid.

Caution: Before executing procedure `DBMS_XMLSCHEMA.copyEvolve`, always back up all registered XML schemas and all XML documents that conform to XML schemas. Procedure `copyEvolve` deletes all documents that conform to registered XML schemas.

First, procedure `copyEvolve` copies the data in schema-based `XMLType` tables and columns to temporary tables. It then drops the tables and columns and deletes the old XML schemas. After registering the new XML schemas, it creates `XMLType` tables and columns and populates them with data (unless the `genTables` parameter is `false`) but it does not create any auxiliary structures such as indexes, constraints, triggers, and row-level security (RLS) policies. Procedure `copyEvolve` creates the tables and columns as follows:

- It creates default tables while registering the new schemas.

- It creates nondefault tables by a statement of the following form:

      CREATE TABLE <TABLE_NAME> OF XMLType OID '<OID>'   XMLSCHEMA <SCHEMA_URL> ELEMENT <ELEMENT_NAME>

  where `<OID>` is the original OID of the table, before it was dropped.

- It adds `XMLType` columns using a statement of the following form:

      ALTER TABLE <Table_Name> ADD (<Column_Name> XMLType) XMLType column
        <Column_Name> xmlschema <Schema_Url> ELEMENT <Element_Name>

When a new schema is registered, types or beans are generated if the registration of the corresponding old schema had generated types or beans. If an XML schema was global before the evolution it will be global after the evolution. Similarly if an XML schema was local before the evolution it will be local (owned by the same user) after the evolution.You have the option to preserve the temporary tables that contain the old documents by passing `true` for the `preserveOldDocs` parameter. In this case, procedure `copyEvolve` does not drop the temporary tables at the end. All temporary tables are created in the database schema of the current user. For `XMLType` tables the temp table will have the following columns:

Table 8-3 XML Schema Evolution: XMLType Table Temporary Table Columns

Name | Type | Comment
--- | --- | ---
`Data` | `CLOB` | XML doc from old table in `CLOB` format.
`OID` | `RAW(16)` | `OID` of corresponding row in old table.
`ACLOID` | `RAW(16)` | This column is present only if old table is hierarchy enabled. `ACLOID` of corresponding row in old table.
`OWNERID` | `RAW(16)` | This column is present only if old table is hierarchy enabled. `OWNERID` of corresponding row in old table.

For `XMLType` columns the temp table will have the following columns:

Table 8-4 XML Schema Evolution: XMLType Column Temporary Table Columns

Name | Type | Comment
--- | --- | ---
`Data` | `CLOB` | XML document from old column in `CLOB` format.
`RID` | `ROWID` | `ROWID` of corresponding row in the table that this column was a part of.

Procedure `copyEvolve` stores information about the mapping from the old table or column name to the corresponding temporary table name in a separate table specified by the `mapTabName` parameter. If `preserveOldDocs` is `true`, the `mapTabName` parameter must not be `NULL`, and it must not be the name of any existing table in the current database schema. Each row in the mapping table has information about one of the old tables/columns. Table 8-5 shows the mapping table columns.

Table 8-5 Procedure copyEvolve Mapping Table

Column Name | Column Type | Comment
--- | --- | ---
`SCHEMA_URL` | `VARCHAR2(700)` | URL of schema to which this table/column conforms.
`SCHEMA_OWNER` | `VARCHAR2(30)` | Owner of the schema.
`ELEMENT_NAME` | `VARCHAR2(256)` | Element to which this table/column conforms.
`TABLE_NAME` | `VARCHAR2(65)` | Qualified Name of table (<owner_name>.<table_name>).
`TABLE_OID` | `RAW(16)` | `OID` of table.
`COLUMN_NAME` | `VARCHAR2(4000)` | Name of column (this will be null for `XMLType` tables).
`TEMP_TABNAME` | `VARCHAR2(30)` | Name of temporary table which holds the data for this table/column.

You can also avoid generating any tables or columns after registering the new XML schema, by using `false` as the `genTables` parameter. If `genTables` is `false`, the `preserveOldDocs` parameter must be `true` and the `mapTabName` parameter must not be `NULL`. This ensures that the data in the old tables is not lost. This is useful if you do not want the tables to be created by the procedure, as described in section "Procedure DBMS_XMLSCHEMA.COPYEVOLVE: Parameters and Errors".

By default it is assumed that all XML schemas are owned by the current user. If this is not true, you must specify the owner of each XML schema in the `schemaOwners` parameter.